home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1999 #2 / Amiga Plus CD - 1999 - No. 2.iso / System-Boost / Sound / XGTool / doc / README < prev   
Encoding:
Text File  |  1998-11-15  |  10.8 KB  |  278 lines
  1. This is the documentation of XGTool V0.9 for Amiga.
  2.  
  3.  
  4.  
  5. Introduction
  6. -----------------------------------------------------------------------------
  7.  
  8. I started to write this program because I needed it. After I had bought my
  9. new shiny Yamaha MU10 external tone generator (11 Jan 1997) I needed a
  10. program to control its rich features. After a lot of trying and restarting
  11. from scratch XGTool was born (around the end of 1997).
  12.  
  13.  
  14.  
  15.  
  16. Legal Stuff - License/Warranty/Disclaimer
  17. -----------------------------------------------------------------------------
  18.  
  19. You may not distribute XGTool for profit except by arrangement with the
  20. author.
  21.  
  22. XGTOOL IS PROVIDED ON THE UNDERSTANDING THAT THE USER ACCEPTS ALL
  23. RESPONSIBILITY FOR USE OF THE PROGRAM. THE AUTHOR WILL NOT BE LIABLE FOR ANY
  24. DAMAGES OR LOSS OF DATA INCURRED BY USE OF THE PROGRAM. THE AUTHOR DOES NOT
  25. GUARANTEE THE PROGRAM IS FIT FOR PURPOSE OR PROVIDE ANY OTHER GUARANTEES OF
  26. MERCHANTABILITY.
  27.  
  28.  
  29.  
  30.  
  31. System Requirements
  32. -----------------------------------------------------------------------------
  33.  
  34. The development and testing configuration for XGTool is:
  35. - Kickstart V39.106
  36. - M68EC020
  37. - MUI V3.8
  38. - blueribbon.library V3.7 (19.12.93)
  39. - The program occupies around 1MB memory (including MUI)
  40. - A 640x400 screen is the minimum
  41.  
  42. If you succeed running XGTool on other configurations, please tell me!!
  43. (address below) I'm especially interested in Enforcer results (whether XGTool
  44. makes any invalid memory accesses). I don't know how to use Enforcer, so if
  45. an XGTool version with debug information is needed for this, please write me
  46. an e-mail, and I send you one.
  47.  
  48.  
  49.  
  50.  
  51. MIDI output
  52. -----------------------------------------------------------------------------
  53.  
  54. XGTool uses either blueribbon.library or midi.library. It fully
  55. cooperates with Bars&Pipes Professional 2.5b (which is the free version on
  56. CompuServe). You can start XGTool behind Bars&Pipes and work with the two
  57. programs together!!
  58.  
  59. Support for midi.library is also implemented.
  60.  
  61. To choose between the two libraries, set the XGTOOLOUT environment variable.
  62. If you have an ENV: assignment, then you can do it by saying in the shell:
  63.  
  64.   setenv XGTOOLOUT MIDI     or    setenv XGTOOLOUT BLUE
  65. If the value is invalid, XGTool will use blueribbon.library by default.
  66.  
  67. Everything is sent as System Exclusive messages. This might change in the
  68. future to controllers, NRPNs, where appropriate. (But some values can only be
  69. set with SysEx-es.)
  70.  
  71.  
  72.  
  73.  
  74. The User Interface
  75. -----------------------------------------------------------------------------
  76.  
  77. The program requires MUI V3.8 or better.
  78.  
  79. The original idea was to imitate the look and feel of XGEdit95, but it would
  80. have required a lot of programming and time, so... You can still discover
  81. ideas stolen from that program.
  82.  
  83. The main adjusting gadget:
  84. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  85. It is a derivation of MUI's numericbutton which is a pop-up slider. The
  86. actual value is written on the slider. If the actual value differs from the
  87. default for that parameter the value is highlighted. (This doesn't work
  88. at the drumnote settings, yet.) As you can see the displayed values are
  89. context sensitive, that is, the reverb time is displayed from 0.3s (second)
  90. to 30s and not from 0 to 127.
  91.  
  92. The value is NOT sent in real time (while you drag the slider). This is a
  93. limitation of MUI's numericbutton class. The value is sent to the synth
  94. ONLY when you release it AND if the value has changed. That is, if you just
  95. press it and release it, without dragging, no value is sent out to the
  96. synth.
  97.  
  98. The graphical display:
  99. ~~~~~~~~~~~~~~~~~~~~~~
  100. It is not implemented, yet. I temporarily removed it. It will appear on the
  101. first (Master) page.
  102.  
  103. The receive lamps:
  104. ~~~~~~~~~~~~~~~~~~
  105. It is not implemented, yet. I temporarily removed it. It will be in the
  106. Controllers section of the Part page. They are switches to enable/disable the
  107. reception of various midi messages.
  108.  
  109. The Instrument List:
  110. ~~~~~~~~~~~~~~~~~~~~
  111.  
  112. If you press the PopUp button on the right of the Instrument Name displayer
  113. in the Part page the Instrument List pops up. Here you can select
  114. instruments. One thing you should know that you can change Banks holding the
  115. right button! A small menu pops up showing the possible Instrument Types
  116. (Ensemble, Brass, Pipe, etc.). Select the type you want to get the list of
  117. instruments of that type. The columns of the Instrument list are: Program
  118. number, Bank number, Name of instrument, and number of elements in that
  119. instrument. After finding the desired instrument, DOUBLE CLICK on that.
  120. This way you permanently selected it. Closing the Instrument List in any
  121. other way (for example, by closing the Instrument List window or pressing the
  122. PopUp button) restores the previously selected instrument for that part.
  123.  
  124. Unfortunately, this doesn't work yet for drumkits. If you browse the
  125. different drumkits in the Instrument List and close the list, your drumnote
  126. settings WILL NOT BE RESTORED. This will be changed in the future.
  127.  
  128.  
  129.  
  130.  
  131. The Future of XGTool
  132. -----------------------------------------------------------------------------
  133.  
  134. This is the first release of the program, V0.9. The version number reflects
  135. that XGTool knows almost everything I wanted her to do. The only major thing
  136. missing is the QS300 editor. This will appear in V1.0. Until V1.0, bugfixes
  137. might appear and other improvements might be implemented.
  138.  
  139. Since I'm writing this program to satisfy my needs it is useless to ask me
  140. to modify XGTool to support your XYZ-1234 tone generator. Since I'm not a
  141. very experienced programmer it took me ages to put XGTool together. It is
  142. usually very hard to implement even my own whishes.
  143.  
  144. However, I probably will be able to deal with questions and wishes related
  145. to MU10 and DB50XG, since this latter seems to be identical to MU10 apart
  146. from the missing AD inputs.
  147.  
  148. If you have any suggestions for improvement you are welcomed to write me an
  149. e-mail. See my address below.
  150.  
  151. If there is something you don't like in XGTool tell me! It can happen that I
  152. agree with you and I change XGTool.
  153.  
  154. You can help improving XGTool!
  155. - I intended to imitate the dial gadgets of XGEdit95, but didn't get the time
  156.   to do it. If you can program MUI and if you are willing to do it, I can
  157.   supply you with graphics and some small program-parts in C which are ready.
  158. - If you have a registered MUI you can make a MUI settings imitating XGEdit95
  159.   If you made one, please send me so I can distribute it together with XGTool
  160.   for the benefit of other users.
  161.  
  162. Other ideas which might get implemented in the future:
  163. - A Tool for Bars&Pipes which sends information about outgoing XG settings
  164.   to XGTool while a song is played. This way you can "rip" a MIDI file's
  165.   XG settings. I do not plan support for MIDI file reading like XGEdit95
  166.   because I know little about MIDI file formats.
  167.  
  168. Already implemented in XGTool but deactivated because not ready:
  169. - Small lamps for every channel to control reception of various messages
  170.   on that channel.
  171. - Editing of User Voices (QS300). It is very preliminary, yet.
  172. - A graphical display to edit certain parameters, like in XGEdit95.
  173.  
  174.  
  175.  
  176.  
  177. Load and Save, File Format
  178. -----------------------------------------------------------------------------
  179.  
  180. Recently I reverse engineered the file format of XGEdit95 and implemented
  181. load/save routines for that. At the beginning XGTool used a custom IFF file
  182. format to save settings. Now the fileformat of XGTool is identical to the
  183. .XGE files of XGEdit. This way the big library of .XGE files will be
  184. available to Amigans, too!
  185.  
  186. The name of the last file you worked with (loaded or saved) can be seen in
  187. the titlebar.
  188.  
  189. Some remarks:
  190. For an MU10 user some of the data in an .XGE file is superfluous:
  191. - Multi EQ settings
  192. - Insertion effects settings
  193. - MultiPart settings for channels 17-32
  194. - Second ADPart settings
  195. - Settings of Drumsets 3-4
  196.  
  197. To write a correct .XGE file, XGTool fills up these parts in the following
  198. manner:
  199.  
  200. - MultiEQ and Insertions: Defaults are written
  201. - MultiPart 17-32: Defaults are written
  202. - Second AD Part: Defaults are written
  203. - Drumsets 3-4: Same as Drumsets 1-2
  204.  
  205. I have not tried what happens when you load an .XGE file prepared for a
  206. higher spec. synth (e.g. Yamaha MU80). These files can contain effect
  207. settings and other settings which are invalid on an MU10 (Distortion or
  208. Aural Exciter effects missing from MU10). Be careful with these files.
  209.  
  210. The directory from which XGTool tries to load a file can be set with the
  211. XGTOOLDIR environment variable. If there is no such variable, the default
  212. directory is the current directory, and the last directory you used for
  213. load/save is stored at program shutdown in the XGTOOLDIR environment
  214. variable. You can set this with the standard AmigaDOS command:
  215.  
  216. setenv XGTOOLDIR "System:MyXGToolFiles"
  217.  
  218.  
  219.  
  220.  
  221. Registration, why?
  222. -----------------------------------------------------------------------------
  223.  
  224. I do not ask for money from XGTool users but I would like to know how many
  225. people use my program. It helps me to decide whether it worths to release
  226. XGTool to the public (thus doing extra work writing the documentation, etc.)
  227. or not.
  228.  
  229. In the "unregistered" version saving is disabled. You can get a fully working
  230. version by sending me and e-mail stating that you are using XGTool, and would
  231. like to use the save function. In return I will send you a patch file (.pch)
  232. for XGTool together with instructions which contains the code for saving.
  233.  
  234. The only information you have to send is your e-mail address where the patch
  235. should be sent. However, I'm very interested in what kind of tone generator,
  236. what Amiga model, etc. you are using. I will be happy if you tell me about
  237. those things but it is NOT necessary for registration.
  238.  
  239. Registered users will automatically get the new versions with saving enabled.
  240.  
  241. Registered user's e-mail address or other information will not be given to
  242. third parties, unless the user agrees that it can be done.
  243.  
  244.  
  245.  
  246.  
  247. Known bugs
  248. -----------------------------------------------------------------------------
  249.  
  250. The following is a bug in Bars&Pipes:
  251.  
  252. When you stop and restart a song in Bars&Pipes, some of your edits will be
  253. lost, because B&P sends those Program Change and Controller messages which
  254. are at the start of a Track when a song is stopped and restarted or when you
  255. rewind a song while it is playing. So it is better to erase all settings from
  256. B&P and leave the job of handling settings to XGTool.
  257.  
  258.  
  259.  
  260.  
  261. How to Reach the Author
  262. -----------------------------------------------------------------------------
  263.  
  264. My name is Csaba Molnár and my e-mail address is:
  265. mc311@ural2.hszk.bme.hu
  266. It is valid until June 1999. After that try mocsa@k2.jozsef.kando.hu, but
  267. it is not guaranteed that it will work. If it doesn't work, look for a new
  268. XGTool version on the Internet. That will contain my new address.
  269.  
  270. New versions are likely to appear
  271. - on the XGTool homepage:
  272.   http://ural2.hszk.bme.hu/~mc311/xgtool/XGTool.html
  273. - on Aminet
  274.   ftp://uk.aminet.net/aminet/mus/midi/XGTool.lha
  275. - on the official Yamaha XG homepage
  276.   http://www.yamaha.co.uk
  277.  
  278.